/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.commons.configuration.tree.xpath;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
import java.util.StringTokenizer;
import org.apache.commons.configuration.tree.ConfigurationNode;
import org.apache.commons.configuration.tree.ExpressionEngine;
import org.apache.commons.configuration.tree.NodeAddData;
import org.apache.commons.jxpath.JXPathContext;
import org.apache.commons.jxpath.ri.JXPathContextReferenceImpl;
import org.apache.commons.lang.StringUtils;
/**
* <p>
* A specialized implementation of the <code>ExpressionEngine</code> interface
* that is able to evaluate XPATH expressions.
* </p>
* <p>
* This class makes use of <a href="http://commons.apache.org/jxpath/">
* Commons JXPath</a> for handling XPath expressions and mapping them to the
* nodes of a hierarchical configuration. This makes the rich and powerful
* XPATH syntax available for accessing properties from a configuration object.
* </p>
* <p>
* For selecting properties arbitrary XPATH expressions can be used, which
* select single or multiple configuration nodes. The associated
* <code>Configuration</code> instance will directly pass the specified
* property keys into this engine. If a key is not syntactically correct, an
* exception will be thrown.
* </p>
* <p>
* For adding new properties, this expression engine uses a specific syntax: the
* "key" of a new property must consist of two parts that are
* separated by whitespace:
* <ol>
* <li>An XPATH expression selecting a single node, to which the new element(s)
* are to be added. This can be an arbitrary complex expression, but it must
* select exactly one node, otherwise an exception will be thrown.</li>
* <li>The name of the new element(s) to be added below this parent node. Here
* either a single node name or a complete path of nodes (separated by the
* "/" character or "@" for an attribute) can be specified.</li>
* </ol>
* Some examples for valid keys that can be passed into the configuration's
* <code>addProperty()</code> method follow:
* </p>
* <p>
*
* <pre>
* "/tables/table[1] type"
* </pre>
*
* </p>
* <p>
* This will add a new <code>type</code> node as a child of the first
* <code>table</code> element.
* </p>
* <p>
*
* <pre>
* "/tables/table[1] @type"
* </pre>
*
* </p>
* <p>
* Similar to the example above, but this time a new attribute named
* <code>type</code> will be added to the first <code>table</code> element.
* </p>
* <p>
*
* <pre>
* "/tables table/fields/field/name"
* </pre>
*
* </p>
* <p>
* This example shows how a complex path can be added. Parent node is the
* <code>tables</code> element. Here a new branch consisting of the nodes
* <code>table</code>, <code>fields</code>, <code>field</code>, and
* <code>name</code> will be added.
* </p>
*
* <p>
* <pre>
* "/tables table/fields/field@type"
* </pre>
* </p>
* <p>
* This is similar to the last example, but in this case a complex path ending
* with an attribute is defined.
* </p>
* <p>
* <strong>Note:</strong> This extended syntax for adding properties only works
* with the <code>addProperty()</code> method. <code>setProperty()</code> does
* not support creating new nodes this way.
* </p>
*
* @since 1.3
* @author Oliver Heger
* @version $Id: XPathExpressionEngine.java 656402 2008-05-14 20:15:23Z oheger $
*/
public class XPathExpressionEngine implements ExpressionEngine
{
/** Constant for the path delimiter. */
static final String PATH_DELIMITER = "/";
/** Constant for the attribute delimiter. */
static final String ATTR_DELIMITER = "@";
/** Constant for the delimiters for splitting node paths. */
private static final String NODE_PATH_DELIMITERS = PATH_DELIMITER
+ ATTR_DELIMITER;
/**
* Executes a query. The passed in property key is directly passed to a
* JXPath context.
*
* @param root the configuration root node
* @param key the query to be executed
* @return a list with the nodes that are selected by the query
*/
public List query(ConfigurationNode root, String key)
{
if (StringUtils.isEmpty(key))
{
List result = new ArrayList(1);
result.add(root);
return result;
}
else
{
JXPathContext context = createContext(root, key);
List result = context.selectNodes(key);
return (result != null) ? result : Collections.EMPTY_LIST;
}
}
/**
* Returns a (canonic) key for the given node based on the parent's key.
* This implementation will create an XPATH expression that selects the
* given node (under the assumption that the passed in parent key is valid).
* As the <code>nodeKey()</code> implementation of
* <code>{@link org.apache.commons.configuration.tree.DefaultExpressionEngine DefaultExpressionEngine}</code>
* this method will not return indices for nodes. So all child nodes of a
* given parent whith the same name will have the same key.
*
* @param node the node for which a key is to be constructed
* @param parentKey the key of the parent node
* @return the key for the given node
*/
public String nodeKey(ConfigurationNode node, String parentKey)
{
if (parentKey == null)
{
// name of the root node
return StringUtils.EMPTY;
}
else if (node.getName() == null)
{
// paranoia check for undefined node names
return parentKey;
}
else
{
StringBuffer buf = new StringBuffer(parentKey.length()
+ node.getName().length() + PATH_DELIMITER.length());
if (parentKey.length() > 0)
{
buf.append(parentKey);
buf.append(PATH_DELIMITER);
}
if (node.isAttribute())
{
buf.append(ATTR_DELIMITER);
}
buf.append(node.getName());
return buf.toString();
}
}
/**
* Prepares an add operation for a configuration property. The expected
* format of the passed in key is explained in the class comment.
*
* @param root the configuration's root node
* @param key the key describing the target of the add operation and the
* path of the new node
* @return a data object to be evaluated by the calling configuration object
*/
public NodeAddData prepareAdd(ConfigurationNode root, String key)
{
if (key == null)
{
throw new IllegalArgumentException(
"prepareAdd: key must not be null!");
}
int index = key.length() - 1;
while (index >= 0 && !Character.isWhitespace(key.charAt(index)))
{
index--;
}
if (index < 0)
{
throw new IllegalArgumentException(
"prepareAdd: Passed in key must contain a whitespace!");
}
List nodes = query(root, key.substring(0, index).trim());
if (nodes.size() != 1)
{
throw new IllegalArgumentException(
"prepareAdd: key must select exactly one target node!");
}
NodeAddData data = new NodeAddData();
data.setParent((ConfigurationNode) nodes.get(0));
initNodeAddData(data, key.substring(index).trim());
return data;
}
/**
* Creates the <code>JXPathContext</code> used for executing a query. This
* method will create a new context and ensure that it is correctly
* initialized.
*
* @param root the configuration root node
* @param key the key to be queried
* @return the new context
*/
protected JXPathContext createContext(ConfigurationNode root, String key)
{
JXPathContext context = JXPathContext.newContext(root);
context.setLenient(true);
return context;
}
/**
* Initializes most properties of a <code>NodeAddData</code> object. This
* method is called by <code>prepareAdd()</code> after the parent node has
* been found. Its task is to interpret the passed in path of the new node.
*
* @param data the data object to initialize
* @param path the path of the new node
*/
protected void initNodeAddData(NodeAddData data, String path)
{
String lastComponent = null;
boolean attr = false;
boolean first = true;
StringTokenizer tok = new StringTokenizer(path, NODE_PATH_DELIMITERS,
true);
while (tok.hasMoreTokens())
{
String token = tok.nextToken();
if (PATH_DELIMITER.equals(token))
{
if (attr)
{
invalidPath(path, " contains an attribute"
+ " delimiter at an unallowed position.");
}
if (lastComponent == null)
{
invalidPath(path,
" contains a '/' at an unallowed position.");
}
data.addPathNode(lastComponent);
lastComponent = null;
}
else if (ATTR_DELIMITER.equals(token))
{
if (attr)
{
invalidPath(path,
" contains multiple attribute delimiters.");
}
if (lastComponent == null && !first)
{
invalidPath(path,
" contains an attribute delimiter at an unallowed position.");
}
if (lastComponent != null)
{
data.addPathNode(lastComponent);
}
attr = true;
lastComponent = null;
}
else
{
lastComponent = token;
}
first = false;
}
if (lastComponent == null)
{
invalidPath(path, "contains no components.");
}
data.setNewNodeName(lastComponent);
data.setAttribute(attr);
}
/**
* Helper method for throwing an exception about an invalid path.
*
* @param path the invalid path
* @param msg the exception message
*/
private void invalidPath(String path, String msg)
{
throw new IllegalArgumentException("Invalid node path: \"" + path
+ "\" " + msg);
}
// static initializer: registers the configuration node pointer factory
static
{
JXPathContextReferenceImpl
.addNodePointerFactory(new ConfigurationNodePointerFactory());
}
}